<?php

namespace App\Services\Bank;

interface BankServiceInterface
{
    /**
     * 联行号增量同步
     *
     * @param string $queryDate 同步日期 (yyyy-MM-dd)
     * @return array
     */
    public function syncBankNumbers(string $queryDate): array;

    /**
     * 联行号查询
     *
     * @param string $bankName 行名关键字 (必填)
     * @param string|null $bankTypeName 行类型名称 (选填)
     * @param string|null $isPreciseQuery 是否精确查询 (1-精确，0-模糊，默认模糊)
     * @return array
     */
    public function queryBankNumbers(string $bankName, ?string $bankTypeName = null, ?string $isPreciseQuery = '0'): array;

    /**
     * 余额查询
     *
     * @param string $bankAcc 银行账号
     * @return array{balance: float|null, available_balance: float|null}
     */
    public function queryBalance(string $bankAcc): array;

    /**
     * 批量代发
     *
     * @param string $erpBatchNo ERP批次号 (必填，保证唯一)
     * @param string $wageTitle 发放标题 (必填)
     * @param string $busiType 发放业务类型 (必填: 1-工资, 2-股权基金分红, 3-其他)
     * @param array $payDetails 付款明细数组
     * @param array $options 其他选项
     * @return array
     */
    public function batchPay(string $erpBatchNo, string $wageTitle, string $busiType, array $payDetails, array $options = []): array;

    /**
     * 代发结果查询
     *
     * @param string|null $erpBatchNo ERP批次号
     * @param string|null $startDate 开始日期 (yyyy-MM-dd)
     * @param string|null $endDate 结束日期 (yyyy-MM-dd)
     * @return array
     */
    public function queryPayResult(?string $erpBatchNo = null, ?string $startDate = null, ?string $endDate = null): array;

    /**
     * 回单批量申请
     *
     * @param array $receiptRequests 回单申请数组
     * @return array
     */
    public function batchApplyReceipt(string $compFlowNo, string $beginDate, string $endDate, array $bankAccounts): array;

    /**
     * 单笔回单下载
     *
     * @param string $receiptNo 回单号
     * @return array
     */
    public function downloadSingleReceipt(string $receiptNo): array;

    /**
     * 当日明细查询
     *
     * @param string $bankAcc 待查询账号 (必填)
     * @param float|null $queryAmtBegin 金额范围起 (选填)
     * @param float|null $queryAmtEnd 金额范围止 (选填)
     * @param string|null $queryCdSign 收支方向 (选填: 0-收入, 1-支出)
     * @param string|null $expandFields 额外字段 (选填，以|分隔，如: serialNo)
     * @return array
     */
    public function queryDailyDetails(string $bankAcc, ?float $queryAmtBegin = null, ?float $queryAmtEnd = null, ?string $queryCdSign = null, ?string $expandFields = null): array;

    /**
     * 历史明细查询
     *
     * @param string $bankAcc 待查询账号 (必填)
     * @param string $queryDateBegin 查询开始日期 (必填，格式: YYYY-MM-DD)
     * @param string $queryDateEnd 查询结束日期 (必填，格式: YYYY-MM-DD)
     * @param float|null $queryAmtBegin 金额范围起 (选填)
     * @param float|null $queryAmtEnd 金额范围止 (选填)
     * @param string|null $queryCdSign 收支方向 (选填: 0-收入, 1-支出)
     * @param string|null $expandFields 额外字段 (选填，以|分隔，如: serialNo)
     * @return array
     */
    public function queryHistoryDetails(string $bankAcc, string $queryDateBegin, string $queryDateEnd, ?float $queryAmtBegin = null, ?float $queryAmtEnd = null, ?string $queryCdSign = null, ?string $expandFields = null): array;

    /**
     * 验证批量代发明细数据格式
     *
     * @param array $payDetails
     * @return array 返回验证结果和错误信息
     */
    public function validatePayDetails(array $payDetails): array;

    /**
     * 获取支付状态
     *
     * @param array $result
     * @return string pending|success|failed|suspicious
     */
    public function getPaymentStatus(array $result): string;

    /**
     * 格式化日期为银行API要求的格式
     *
     * @param mixed $date
     * @return string
     */
    public function formatDate($date): string;

    /**
     * 同步银行明细到数据库
     *
     * @param string $bankAcc 银行账号
     * @param int $days 同步天数，1表示当日，大于1表示历史明细
     * @param string|null $syncBatchId 同步批次ID，为空则自动生成
     * @return array 返回同步结果
     */
    public function syncDetailsToDatabase(string $bankAcc, int $days = 1, ?string $syncBatchId = null): array;

    /**
     * 获取同步统计信息
     *
     * @param string|null $syncBatchId 指定批次ID，为空则获取最新批次
     * @return array
     */
    public function getSyncStats(?string $syncBatchId = null): array;

    /**
     * 执行充值匹配算法
     *
     * @param array $options 匹配选项
     * @return array 返回匹配结果
     */
    public function runRechargeMatching(array $options = []): array;

    /**
     * 手动确认匹配
     *
     * @param int $rechargeId 充值申请ID
     * @param int $bankDetailId 银行明细ID
     * @param int|null $operatorId 操作人ID
     * @return array 返回操作结果
     */
    public function confirmMatch(int $rechargeId, int $bankDetailId, ?int $operatorId = null): array;

    /**
     * 取消匹配
     *
     * @param int $rechargeId 充值申请ID
     * @param int|null $operatorId 操作人ID
     * @return array 返回操作结果
     */
    public function cancelMatch(int $rechargeId, ?int $operatorId = null): array;
}
